//! 命名服务trait定义
//!
//! 提供服务注册、发现、健康检查等核心功能的接口定义
//!
//! # 功能概述
//! - 服务注册：支持服务实例的动态注册
//! - 服务发现：支持基于命名空间和分组的实例发现
//! - 健康检查：自动检测服务实例的健康状态
//! - 事件订阅：支持服务变更的事件通知机制
//! - 负载均衡：支持多种负载均衡策略
//!
//! # 架构设计
//! - 分层架构：接口层与实现层分离，支持多种实现方案
//! - 异步设计：所有操作均为异步接口，支持高并发场景
//! - 事件驱动：基于事件总线的服务变更通知机制
//! - 零拷贝：最小化数据传输过程中的内存拷贝

use async_trait::async_trait;
use crate::{Result, ServiceInstance, EventListener};

/// 命名服务trait
///
/// 定义服务注册、发现、健康检查等核心功能的统一接口
///
/// # 方法说明
/// 所有方法均为异步接口，支持高并发场景下的服务操作
#[async_trait]
pub trait NamingService: Send + Sync + std::fmt::Debug {
    /// 注册服务实例
    ///
    /// # 参数
    /// - `instance`: 服务实例信息，包含IP、端口、权重等属性
    ///
    /// # 返回值
    /// 成功返回Ok(())，失败返回错误信息
    async fn register_instance(&self, instance: &ServiceInstance) -> Result<()>;

    /// 注销服务实例
    ///
    /// # 参数
    /// - `namespace`: 命名空间，用于逻辑隔离
    /// - `group`: 服务分组，支持按环境、版本等维度分组
    /// - `service_name`: 服务名称
    /// - `instance_id`: 实例唯一标识符
    ///
    /// # 返回值
    /// 成功返回Ok(())，失败返回错误信息
    async fn deregister_instance(&self, namespace: &str, group: &str, service_name: &str, instance_id: &str) -> Result<()>;

    /// 获取健康的服务实例
    ///
    /// # 参数
    /// - `namespace`: 命名空间
    /// - `group`: 服务分组
    /// - `service_name`: 服务名称
    ///
    /// # 返回值
    /// 返回健康状态的服务实例列表，按权重排序
    async fn get_healthy_instances(&self, namespace: &str, group: &str, service_name: &str) -> Result<Vec<ServiceInstance>>;

    /// 获取所有服务实例
    ///
    /// # 参数
    /// - `namespace`: 命名空间
    /// - `group`: 服务分组
    /// - `service_name`: 服务名称
    ///
    /// # 返回值
    /// 返回所有服务实例列表，包括健康和不健康的实例
    async fn get_all_instances(&self, namespace: &str, group: &str, service_name: &str) -> Result<Vec<ServiceInstance>>;

    /// 获取单个服务实例
    ///
    /// # 参数
    /// - `namespace`: 命名空间
    /// - `group`: 服务分组
    /// - `service_name`: 服务名称
    /// - `instance_id`: 实例唯一标识符
    ///
    /// # 返回值
    /// 返回指定实例，不存在时返回None
    async fn get_instance(&self, namespace: &str, group: &str, service_name: &str, instance_id: &str) -> Result<Option<ServiceInstance>>;

    /// 更新服务实例
    ///
    /// # 参数
    /// - `instance`: 更新后的服务实例信息
    ///
    /// # 返回值
    /// 成功返回Ok(())，失败返回错误信息
    async fn update_instance(&self, instance: &ServiceInstance) -> Result<()>;

    /// 获取所有服务名
    ///
    /// # 参数
    /// - `namespace`: 命名空间
    /// - `group`: 服务分组，None表示获取所有分组的服务
    ///
    /// # 返回值
    /// 返回指定命名空间和分组下的所有服务名称列表
    async fn get_all_service_names(&self, namespace: &str, group: Option<&str>) -> Result<Vec<String>>;

    /// 订阅服务变更事件
    ///
    /// # 参数
    /// - `namespace`: 命名空间
    /// - `group`: 服务分组
    /// - `service_name`: 服务名称
    /// - `listener`: 事件监听器，用于接收服务变更通知
    ///
    /// # 返回值
    /// 成功返回Ok(())，失败返回错误信息
    async fn subscribe_service(&self, namespace: &str, group: &str, service_name: &str, listener: Box<dyn EventListener>) -> Result<()>;

    /// 取消订阅服务变更事件
    ///
    /// # 参数
    /// - `namespace`: 命名空间
    /// - `group`: 服务分组
    /// - `service_name`: 服务名称
    /// - `listener_name`: 监听器名称
    ///
    /// # 返回值
    /// 成功返回Ok(())，失败返回错误信息
    async fn unsubscribe_service(&self, namespace: &str, group: &str, service_name: &str, listener_name: &str) -> Result<()>;

    /// 处理服务心跳
    ///
    /// # 参数
    /// - `namespace`: 命名空间
    /// - `group`: 服务分组
    /// - `service_name`: 服务名称
    /// - `instance_id`: 实例唯一标识符
    ///
    /// # 返回值
    /// 成功返回Ok(())，失败返回错误信息
    async fn handle_heartbeat(&self, namespace: &str, group: &str, service_name: &str, instance_id: &str) -> Result<()>;
}